Command line client
Introduction The LPU command line client is provided as a default (and very basic) client allowing to perform most of the operations allowed by the LPU. The command lines may be executed from any bash terminal (e.g. natively on Linux and Mac OS/X computers), provided they have an Internet connection to a LPU server. It's general syntax is: $ ./lpu --command arguments Where: *command is one of the available commands, as listed in the table below. *arguments is a series of arguments and options, the usage of which depend on the selected command; Example: $ ./lpu --info Version: 3.0b2 Functions: 0 Projects: 1 Some default values are defined in the Command Line Configuration File. There are two general options: Please refer also to Installing the command line client. The possible commands are summarized in the table below: =Detailed command descriptions= add-aggregator Add an aggregator to a dimension ./lpu --add-aggregator --dimension dimension --function function *''dimension'' : Identification (numeric id) of the dimension (see About identification below) *''function'' : Identification (name or id) of the function (idem) This command adds the specified function to the specified dimension as an aggregator. This imposes that the function has been declared as an aggregating function and that it's arguments and return types are compatible with the value type of the dimension add-to-collection Add an artefact to a collection ./lpu --add-to-collection --artefact artefact --collection collection *collection'' : Identification of the collection (see About identification below) *artefact : Identification of the artefact (idem) This command adds the identified artefact to the identified collection. Note that there might be some restrictions to the operation (e.g. it is forbidden to add artefacts to some dynamically defined collection). load-artefact Load artefact(s) into the server $ ./lpu --load-artefact --dimension ''dimension --file file --collection collection *''dimension'' : Identification of the dimension (see About identification below) *''file'' : Path to the file(s) containing the artefact data *''collection'': (optional) Identification of the collection to which artefacts are added IMPLEMENTED |} This command upload the content of the file(s) as artefacts into the identified dimension. It is possible to specify more than one files using name patterns, protected with quotes. It is not possible to add several files by specifying the -a option more than once. ./lpu --load-artefact --dimension 1 --file myfile.txt → Valid ./lpu --load-artefact --dimension 1 --file ”./*.txt” → Invalid, the file ./*.txt does not exist! ./lpu --load-artefact --dimension 1 --file ./*.txt → Valid (all txt files will be loaded) ./lpu --load-artefact --dimension 1 --file file1.txt file2.txt → Valid NOT YET IMPLEMENTED: If a collection is also identified, the artefacts will be also added to the collection new-collection Create a new collection $ ./lpu --new-collection --dimension dimension --collection collection *''dimension'': Identification of the dimension (see #about-identification below) *''collection'' (or --name collection): Name of the collection to create (must be unique within the dimension) This command creates a new, empty, collection into the identified dimension. new-dimension Create a new dimension *--project project : Identification of the project (see About identification below) *''dimension'' (or --name name): Name of the dimension to create (must be unique within the project) type : Type of the artefact data in this dimension This command creates a new, empty, dimension into the identified project. The type of artefacts may be: text, integer, decimal or boolean. new-function Create a new function $ ./lpu --new-function --name function --language language --usage usage --input input --output output [--argument arg,opt,default] [--requires require] [--file path] *function (or --name name): Name of the function to create (must be unique) *''language'' : Language of the function's source code *''usage'' : Intended usage of the function *''input'' : Type of data used by the function *''output'' : Type of data returned by the function *''argument'' : Argument to the function, see below (this option may appear more than once if there is more than one argument) *''requires'' : name of functionalities required to execute the function *''path'' : path to the file containing the function's source code (optional, if missing the code will be read from stdin) This command creates a new function, suitable for the intended usage, which may be: projection, aggregation, segmentation or fusion. A function declared for one usage may not be used in another usage. The arguments of a function are parameters that affect the way the function behaves. For example: the pattern of a pattern matching function. There may be more than one argument, and hence the option my appear more than once. Each argument descriptions is made of three elements: #the name of the argument (mandatory); #the second element indicates whether the argument is optional (“yes”) or mandatory (“no”, default); #the third element is the default value, when the argument is optional; The elements are separated by commas, without spaces (see example below) The command will read the source code from the standard input. Use a redirection to input source code from a file. For example: $ ./lpu --new-function --name MyFunction --language plperl --argument pattern -output text --input text < source-code.pl $ ./lpu --new-function --name MyFunction2 --language plperl --argument pattern,yes,"." -output text --intput text --file source-code.pl Refer to the section about Library Functions for explanations about how to write the source code. new-project Create a new project $./lpu --new-project --project name $./lpu --new-project --name name *''name"": Name of the project to create (must be unique) This command creates a new empty project. new-projection Create a new projection $./lpu --new-projection --name name --project project --from source --to target --function function [--argument arg=''value''] *''name'' : Name of the projection to create *''project'': Name or id of the project *''source'' : Identification of the dimension which will be used as source dimension *''target'': Identification of the dimension which will be used as target dimension *''function'' : Name or id of the function to used to compute the projection *''argument'' Value of the arguments (if the function requires them) This command installs a new projection between the source and target dimensions, using the identified function. For example: $ ./lpu --new-projection --name MyProj --project 1 --function MyFuntion2 --argument pattern="a-z+" --from 1 --to 2 delete-artefact Delete an artefact $ ./lpu --delete-artefact --artefact artefact $ ./lpu --delete-artefact --id artefact *''artefact'' Identification of the artefact to delete This command deletes an artefact from the server and, as a consequence, all of its projections. delete-dimension Delete a dimension $ ./lpu --delete-dimension --dimension dimension $ ./lpu --delete-dimension --id dimension *''dimension''Identification of the dimension to delete This command deletes a dimension from the server and, as a consequence, all its artefacts, collections and the projections which refer to this dimension as source or target. delete-function Delete a function $ ./lpu --delete-function --function function $ ./lpu --delete-function --id function $ ./lpu --delete-function --name function *''function'' Identification (name or id) of the function to delete (see About identification below) This command deletes a function from the server and, as a consequence, all the projections that use it, as well as all segments and/or aggregates that used it. delete-project Delete a project $ ./lpu --delete-project --name project $ ./lpu --delete-project --id project $ ./lpu --delete-project --project project *''project'' (or --id id, or --name name) : Identification of the project to delete This command deletes a project. (Note: until version 3.0b2, the command does not delete non empty projects). delete-projection Delete a projection $ ./lpu --delete-projection --id projection $ ./lpu --delete-projection --projection projection *'projection'' Identification of the projection to delete This command deletes a projection; as a consequence it also removes all artefact and collection images computed for this projection. delete-collection Delete a collection $ ./lpu --delete-collection --id collection $ ./lpu --delete-collection --collection collection *''collection''Identification of the collection to delete This command deletes a collection and all of its images. The artefacts are not deleted;, they remain in the dimension. get-artefact Retrieve the description of an artefact $ ./lpu --get-artefact --id artefact $ ./lpu --get-artefact --artefact artefact *''artefact'' : Identification of the artefact This command displays information about an artefact an displays it; the content of the artefact is not displayed. get-content Retrieve the content of an artefact $ ./lpu --get-content --id artefact $ ./lpu --get-content --artefact artefact *''artefact'' : Identification of the artefact This command displays the content of the identified artefact. get-collection Retrieve the description of a collection $ ./lpu --get-collection --id collection $ ./lpu --get-collection --collection collection *''collection'': Numeric identification of the collection This command displays information about a collection: name, dimension, elements, images, etc. get-dimension Retrieve the description of a dimension $ ./lpu --get-dimension --id dimension $ ./lpu --get-dimension --dimension dimension *''dimension'' Numeric identification of the dimension This command displays information about a dimension: name, artefacts, collections, etc. get-function Retrieve the description of a function $ ./lpu --get-function --id function $ ./lpu --get-function --function function $ ./lpu --get-function --name function *''function'' Identification of the function This command displays information about a function: name, arguments, etc. get-projection Retrieve the description of a projection $ ./lpu --get-projection --id projection $ ./lpu --get-projection --projection projection *''projection'' Identification of the projection This command displays information about a projection: name, dimensions, function, etc. get-project Retrieve the description of a project $ ./lpu --get-project --id project $ ./lpu --get-project --name project $ ./lpu --get-project --project project *''project'' Identification of the project (name or id) This command displays information about a project: name, dimensions, etc. info Retrieve information about the server $ ./lpu --info This command displays information about the server: version of the software and of the database system, list of projects, etc. list-collections Retrieve the list of collections in a dimension $ ./lpu --list-collections --dimension dimension *''dimension'' Identification (id) of the dimension This command displays the list of collections in the identified dimension. list-dimensions Retrieve the list of dimensions in a project $ ./lpu --list-dimensions --project project *''project'' : Identification of the project (name or id) This command displays the list of collections in the identified project. list-functions $ ./lpu --list-functions This command displays the list of functions in the server. list-projections Retrieve the list of projections in a project $ ./lpu --list-projections --project project *''project'' : Identification of the project (name or id) This command displays the list of projections in the identified project. list-projects Retrieve the list of projects $ ./lpu --list-projects This command displays the list of projects in the server. =Identifying LPU objects by name and id= Each object in the LPU is identified by a unique number in its category. The numbers are unique across projects. Hence, the --project, --dimension, --collection, --artefact, --function and --projection arguments may use a number to identify uniquely each of these object. In addition, the LPU also allow to give names to objects. However, the names are unique in their context only: *Project names are unique; *Dimension names are unique within a project; *Collection and artefact names are unique within a dimension; *Function names are unique; *Projection names are unique within a project; Unfortunately, the basic command line client does not allow to take advantage of this feature. As a consequence, dimensions, collections, projections and artefacts must always be identified by their numeric id even when the id could be in theory guessed from the context. *The rules for collections, projections and artefacts are the same. *The rules for functions and projects are the same. Examples: Be aware that the shell is sensitive to spaces. Hence, if the version of the LPU you use allows for spaces in names, then you have to protect them with quotes, like in: –project “My Project”. =Installing the command line client= To install the command line client, follow these steps: #Make sure that you have perl 5 installed on your computer; #Make sure that the SOAP Lite perl library is installed #*On Linux systems, this is done by installing the libsoap-lite-perl package #*On MAC OS/X systems, install the SOAP::Lite package from a CPAN mirror (this requires XCode - free from the Mac App Store) #Copy the lpu.pl file in any directory and make the file executable #Optionally symlink it to ./lpu for your convenience #If you don't want to enter the URL of the LPU server every time, edit the config.pl file in the same directory as the lpu.pl file #*There must be at least one line: #*$server = "http://my.lpu.server/lpu"; #*Where, of course, "my.lpu.server" is replaced by the name or IP Adress of the LPU server You are ready to run. The command line tool has not been tested on windows systems, but since it is a perl program, it should be portable.